home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
HPAVC
/
HPAVC CD-ROM.iso
/
STDERRF.ZIP
/
STDERRF.DOC
< prev
next >
Wrap
Text File
|
1995-05-29
|
37KB
|
1,021 lines
STDERRF
A STDERR Redirection Utility
Version 1.00
USER'S GUIDE
MoonWare
16005 Pointer Ridge Drive
Bowie, MD 20716-1744
raymoon@dgs.dgsys.com
Copyright 1995 Raymond Moon
ALL RIGHTS RESERVED
LIMITED WARRANTY - STDERRF is provided AS IS.
MoonWare makes no representations or warranties, expressed or im-
plied, about the contents hereof, including, without limitations,
any implied warranties of merchantability or fitness for a
particular purpose, all of which MoonWare expressly disclaims.
Neither MoonWare, nor anyone involved in the distribution of this
software shall be liable for any direct, indirect, consequential,
or incidental damages arising out of the use, the results of use,
or inability to use such product even if I have been advised of
the possibility of such damages or claim.
USER'S GUIDE COPYRIGHT NOTICE
Copyright (c) 1995 by Raymond Moon
ALL RIGHTS RESERVED
Users for their personal use may reproduce this manual by print-
ing it or coping it onto disk for automated access.
SOFTWARE COPYRIGHT NOTICE
Copyright (c) 1995 by Raymond Moon
ALL RIGHTS RESERVED
The STDERRF software is copyright (c) 1995 by Raymond Moon. It may
be used without fee for non-commercial use. Commercial use
requires prior written agreement of the author.
SOURCE CODE COPYRIGHT NOTICE
Copyright (c) 1995 by Raymond Moon
ALL RIGHTS RESERVED
The source code is copyright (c) 1995 by Raymond Moon. The source
code, in part or whole, and any derivative work can be used
royalty free for non-commercial use as long as my copyright is
included in the documentation. To distribute the source code, in
part or whole, and any derivative work must include my copyright
and source code restrictions and requires prior written agreement
of the author.
SHAREWARE DISTRIBUTION
I have chosen this method of distributing the STDERRF software so
you, the user, can obtain and use STDERRF with a minimum of
inconvenience. Users are authorized to upload the zip file,
STDERRF.ZIP, to any Internet Node providing shareware software
distribution or dial-up Bulletin Board System as long as the zip
file has not been modified.
ii
CHARGES FOR DISTRIBUTION
STDERRF cannot be sold without the author's prior written approv-
al. If a third party distributes STDERRF on a diskette, which
third party can charge a small fee not to exceed $5.00 per
diskette or $30.00 for CD-ROM to cover the cost of the media and
any shipping costs.
iii
TABLE OF CONTENTS
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 What is STDERRF . . . . . . . . . . . . . . . . . . . 1
1.2 Summary of STDERRF Usage . . . . . . . . . . . . . . . 1
1.3 Hardware Requirements . . . . . . . . . . . . . . . . 1
1.4 Printing this Manual . . . . . . . . . . . . . . . . . 2
1.5 User Responsibilities . . . . . . . . . . . . . . . . 2
1.6 User Comments . . . . . . . . . . . . . . . . . . . . 2
BASICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1 STDERRF PURPOSE . . . . . . . . . . . . . . . . . . . 3
2.2 STDERRF ALGORITHM . . . . . . . . . . . . . . . . . . 3
2.3 STDERRF SOURCE FILES . . . . . . . . . . . . . . . . . 4
2.4 DETAILED DESCRIPTION OF SOURCE CODE FILES . . . . . . 4
2.4.1 Startup1.asm . . . . . . . . . . . . . . . . . . 4
2.4.2 Stderrf.asm . . . . . . . . . . . . . . . . . . 5
2.4.3 Exit.asm . . . . . . . . . . . . . . . . . . . . 7
2.4.4 Getvldc.asm . . . . . . . . . . . . . . . . . . 7
2.4.5 Stderrf.inc . . . . . . . . . . . . . . . . . . 7
2.4.6 Procesor.inc . . . . . . . . . . . . . . . . . . 7
PRINTDOC . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.1 Using PRINTDOC . . . . . . . . . . . . . . . . . . . . 8
STDERRF ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . 9
4.1 Error Messages . . . . . . . . . . . . . . . . . . . . 9
4.2 Non-DOS Related Error Messages . . . . . . . . . . . . 9
4.2.1 Usage . . . . . . . . . . . . . . . . . . . . . . 9
4.2.2 STDERRF terminated at user's request . . . . . . 9
4.3 DOS related Errors . . . . . . . . . . . . . . . . . . 9
4.3.1 Unable to duplicate STDERR filehandle . . . . . . 9
4.3.2 Unable to create redirection file . . . . . . . . 10
4.3.3 Unable to force STDERR to redirection filehandle
. . . . . . . . . . . . . . . . . . . . . . . . . 10
4.3.4 Unable to load and execute program . . . . . . . 10
4.3.5 Unable to restore STDERR . . . . . . . . . . . . 11
4.3.6 Unable to close redirection file . . . . . . . . 11
REGISTRATION . . . . . . . . . . . . . . . . . . . . . . . . . 12
Registration Information . . . . . . . . . . . . . . . . . . 12
STDERRF Registration Form . . . . . . . . . . . . . . . . . 13
iv
INTRODUCTION
1.1 What is STDERRF
====================
STDERRF is an STDERR, standard error, redirection utility.
The DOS command line only allows for redirection of STDOUT,
standard out, to be redirected from the screen to a file or
device. This feature allows the software author to ensure that
certain messages that require human intervention are not redi-
rected into a file but displayed on the screen. STDERRF will
force STDERR to be redirected to a file of the user s choice.
STDERRF and its assembly language source code provides a
complete working example on redirecting STDERR to a file.
STDERRF source code was too large to include it in the Frequently
Asked Questions (FAQ) for the alt.lang.asm and comp.lang.asm.x86
newsgroups. Therefore, I have distributed it as Shareware so
that STDERRF is readily available to anyone who wants it. This
program is meant to be an instructional not a commercial product.
1.2 Summary of STDERRF Usage
============================
STDERRF FILENAME EXENAME [ COMMAND LINE ]
where:
FILENAME is the name of the file into which the user
wants the STDERR to be redirected. If the drive or
path specified is not included, the file will be
created in the default directory. If the file ex-
ists, STDERRF will ask the user whether to continue.
If the user wants to continue, STDERRF will ask if
the file is to be truncated, i.e., contents
overwritten, or the new output appended to the cur-
rent contents.
EXENAME is the file name and extension, the extension is
required, of the program to execute
1.3 Hardware Requirements
==========================
IBM PC/XT/AT/PS/2 or 100% compatible personal computer
PC-DOS or MS-DOS 2.0 or higher
3K memory
80286 or better processor
1
INTRODUCTION
============
1.4 Printing this Manual
=========================
This User's Guide has been formatted so you can print it on
most LaserJets and DeskJets that print 60 lines per page and 10
cpi. To print this User's Guide, use the following DOS command.
COPY STDERRF.DOC PRN:
This example assumes that STDERRF.DOC is in the default direc-
tory.
If your printer does not print 60 lines per page as shown by
the page breaks creeping up or down the page, see the section on
Using PRINTDOC, page 8.
1.5 User Responsibilities
==========================
As mentioned earlier, STDERRF is being distributed as Share-
Ware. STDERRF is meant to provide a full working example of how
to redirect STDERR to a file. While there is no request for
payment for non-commercial use, STDERRF is not released to the
Public Domain. If you use my code or derive code from my code
for non-commercial purposes, you must include my copyright in
your source code and documentation, and include my restricted
rights for usage if the source code is published. This is all I
ask. If you want use my code or derive code for my code for
commercial purposes, you must register your copy. See Registra-
tion, page 12 If you implement the algorithm without referring
to my code, no restrictions apply.
1.6 User Comments
==================
User comments are appreciated at any time. Please send any
comments to:
raymoon@dgs.dgsys.com
or
Raymond Moon
16005 Pointer Ridge Drive
Bowie, MD 20716-1744
2
STDERRF BASICS
2.1 STDERRF PURPOSE
====================
The purpose of STDERRF is to teach and not to be commercial
utility. I did write a full featured utility so that you could
see a full and working implementation. The source code can be
used for more than just learning how to redirect STDERR. My
source code can show you how to have standardized startup code
that will provide command line arguments in argc and *argv[]
format just as in C. Also, this source code illustrates how to
write a procedure that will assemble in any memory model.
STDERRF.ASM also is a good example of how to load and execute
another program with all the supporting structures. GETVLDC.ASM
is a general purpose library procedure that will return the
user s response to a question. This procedure can go directly
into your library. Lastly, EXIT.ASM shows any easy way to write
an error exit routine that lets the user know why the program is
terminating.
2.2 STDERRF ALGORITHM
======================
The basic algorithm for STDERRF is:
1. Accepts three command line arguments:
a. The full path and filename of the file into which
STDERR is to be written.
b. The full path and filename of the program to be
executed.
c. The command line for the program to be executed
(should be delimited by double quotes to allow multi-
ple arguments). This argument is optional.
2. Releases all memory above the program using Int 21 func-
tion 4ah so that there will be room enough to load and
execute the designated program.
3. Opens the file from step #1.a above into which STDERR is
to be written. If file exists, ask user to continue. If
to continue, ask user if the file is to be truncated or
output appended. Perform the requested actions.
4. Duplicates STDERR filehandle using Int 21h function 45h.
5. Uses Int 21h function 46h, force STDERR filehandle to
have the filehandle of the opened file from step #2.
6. Uses Int 21h function 4b00h to load and execute the
program from step #1.a. Use the default environment and
the command line from step #1.c above.
3
STDERRF BASICS
==============
7. Upon return from the function 4b00h, closes the file
opened in step #2.
8. Restores STDERR using Int 21h function 46h to force
STDERR to point to the filehandle saved from step #3
above.
2.3 STDERRF SOURCE FILES
=========================
The STDERRF source files with general descriptions are:
STARTUP1.ASM General Purpose ASM Startup Code
Used to parse command line and
Free up memory above the program
STDERRF.ASM Main Procedure for STDERRF
Implements the basic algorithm
STDERRF.INC Include file for all STDERRF source
files.
GETVLDC.ASM Library procedure to get a user s
response to a question.
EXIT.ASM STDERRF abnormal termination
procedure.
PROCESOR.INC Ensures all files assembled for the
same processor.
STARTUP1.ASM implements steps #1 and #2 of the algorithm.
STDERRF.ASM implements steps #3 through #8.
2.4 DETAILED DESCRIPTION OF SOURCE CODE FILES
==============================================
2.4.1 Startup1.asm
-------------------
As stated above, this is one of my standard assembly startup
procedures. This startup code performs the following functions:
1. Parses the command line into argc and *argv[] similar to
C. Argv[0] is the first command line argument not the program
name as in C.
2. Initializes the following global variables:
a. DGRP, segment address of DGROUP
b. STACK_BOTTOM, offset to stack bottom in DGROUP
c. PSP, segment address of PSP
d. ENVIRON, segment address of passed copy of the ENVI-
RONMENT
e. OSMAJOR, integer part of OS system
f. OSMINOR, decimal part of OS system
4
STDERRF BASICS
==============
3. If DOS version is less than 2.0, aborts with error mes-
sage.
4. Initializes DS and ES segment registers to DGROUP.
5. Shrinks memory down to size of program by releasing all
memory above program.
This procedure is one of a set of startup code range from the
very simple to the one above this one that also parses the
environmental strings. By mid-summer 1995, I should have all the
procedures available.
2.4.2 Stderrf.asm
------------------
This procedure is the heart of this program. As stated above,
this procedure implements steps #3 through to the end of the
algorithm.
STDERRF.ASM starts executing by telling the user who it is.
Then, it checks to see that there are at least two command line
arguments, the redirection file and the program to execute. If
there is not at least two arguments, the program displays an
error message and terminates.
The next step is the first that implements the algorithm. A
duplicate file handle for STDERR is created. To be a well
behaved program, STDERR needs to be restored at the end of the
program so a copy of it must be saved. I save it to a global
variable because the EXIT procedure checks to see if it is zero.
If it is not zero, the EXIT procedure will know that STDERR has
not been restored and will attempt restore it.
The next step is to initialize the command tail for the program
to be executed. The command tail is copied into the last 128
bytes of the PSP of the program to be executed. I created a
structure to make the addressing of its various parts easier.
The structure is:
CommandTail_S struc
ctLength db ? ; Length of command tail minus end CR
ctLeadingSpace db ? ; Initial space to start command tail
ctText db 126 dup (?) ; Command Tail
CommandTail_S ends
The first byte is the length of the command tail which does not
include the terminating carriage return. The command tail starts
with a space; this is the space between the end of the filename
typed in at the DOS prompt and the first command line argument.
Microsoft recommends that a space be placed there, and I have
followed their recommendation. That leaves 126 bytes for the
command line. My code does not check the length because the
command line for the executed program is one of three command
5
STDERRF BASICS
==============
line arguments so it must be less than 126. The code should be
straight forward. I load the bytes one at a time and count each
one. At the end, I terminate the string with a carriage return
and store the length in the first byte.
The next nine blocks deal with opening the file into which STDERR
will be redirected. I first try to open the file to see if the
file already exists. If the file does exist, STDERRF asks the
user if he wants to continue. If the user wants to continue,
STDERRF asks the user if the redirection is to be appended or
overwritten. Based upon the user s response, the read/write
pointer is moved to the end of the file or the start of the file
and zero bytes written. If the file does not exist, it is
created.
Now, the next block forces STDERR to have the filehandle of the
just opened file. When STDERRF opened the file, the
NO_INHERITANCE flag was not set. Therefore, when STDERRF loads
and executes the target program, that program will inherit STDERR
pointing to the file vice to the console.
Everything is now set to load and execute the desired program.
The next block does this. Now I need to explain the ParamBlk
structure. This structure is defined as:
LoadExec_S struc
leEnvironment dw ? ; Environment block segment address
leCommandTail LPtr <> ; Address of Command Tail
leFCB_1 LPtr <> ; address of default FCB, #1
leFCB_2 LPtr <> ; address of second FCB, #2
LoadExec_S ends
(The LPtr is another structure that allow me to address the
segment and offset portions of a long pointer independently.)
The initialization of this structure is done in the .DATA seg-
ment. leEnvironment is set to 0 so that STDERRF s environment is
used. This variable provides you with the capability to define a
tailored environment for the executed program. The command tail
is explained above. The last two entries are the default and
second File Control Blocks (FCBs). Again, Microsoft recommends
that these FCBs be initialized to blank FCBs. A minimum blank
FCB is defined as:
EmptyFCB db 11 dup (20h), 5 dup (00h)
You can see that both FCBs are initialized to the same empty FCB.
If the load and execute is successful, STDERRF restores STDERR by
forcing it to point to the saved filehandle for STDERR. Then the
redirected file is closed, and STDERRF terminates by returning
the exit code of the executed program.
6
STDERRF BASICS
==============
2.4.3 Exit.asm
---------------
While this is not a standard library routine of mine, it is a
regular procedure in all my programs. This procedure follows the
same format. When I encounter a terminal error in some part of
the program, I call this procedure with an equate stored in the
AX that identifies the error type. The EXIT procedure uses this
value as an index into arrays that store the address and length.
2.4.4 Getvldc.asm
------------------
This is a standard library procedure. It is actually new in that
I modified an earlier procedure that was hard coded for the
(y/n) response. Now, it is a general procedure. In fact, my
first interaction had one question to the user as truncate or
append? (t/a): . Looking at it, I realized that it should be
overwrite or append? (o/a): . The modification was just in the
string variable that contained the question and passed valid
choices in STDERRF.ASM. No changes were required in GETVLDC.ASM.
This is how procedures should be written.
2.4.5 Stderrf.inc
------------------
There is nothing unique there. I just have combined equates,
macro, etc. used in two or more procedures in this include file.
This ensures that the information is uniform in all source files.
2.4.6 Procesor.inc
-------------------
This include file contains only the processor directive. Again,
using this include file ensures that all files are processed
using the same processor instruction set. It also provides a
single location to modify to change the processor.
7
PRINTDOC
3.1 Using PRINTDOC
===================
If you have a LaserJet or DeskJet printer set to other than
60 lines per page, you may need to use PRINTDOC to print a copy
of this manual.
How do you know that you need to use PRINTDOC. When you
printed this manual using the DOS COPY command, the page breaks
creep down the page.
First you must determine in which direction and how many
lines the offset is. Find pages 5, 6, and 7. The top of each of
these pages starts with a header, STDERRF BASICS with double
underline, flush on the right margin. Count the number of lines
this header is shifted. Add this number to 60. This is the
number to put on PRINTDOC's command line.
Make sure that STDERRF.DOC is present in the default directo-
ry with PRINTDOC. Print this manual by using the following
command line:
PRINTDOC xx
where xx is the number you determined above. Only values
between 61 and 84 are valid.
All PRINTDOC does is to adjust the top margin. It cannot be
use to print this manual on less pages by using legal sized
paper.
For values of 66 and less, PRINTDOC will split the difference
between the top and bottom margins. For values above 66,
PRINTDOC keeps a one inch top margin, that is six lines, and puts
the excess lines into the bottom margin.
PRINTDOC directs the printed output to the DOS PRN: device.
If your printer is connected to any other port than LPT1:, you
must use the DOS MODE command to redirect the output to that
port. See your DOS manual on how to do this.
8
STDERRF ERROR MESSAGES
4.1 Error Messages
===================
STDERRF displays two different types of error messages. The
first type is displayed when a non-DOS related error condition
occurs. The second is displayed when the error is DOS related.
Error Messages are displayed on the screen when STDERRF must
terminate due to an unrecoverable condition or at user direction.
4.2 Non-DOS Related Error Messages
===================================
The following error messages are the non-DOS related messages
with an explanation for when they occur.
4.2.1 Usage
-----------
The usage message which explains the basic command line options
is displayed whenever the number of command line arguments is
less than two, the minimum allowed. This is a quick way to
display the help when the program is executed without any command
line arguments.
4.2.2 STDERRF terminated at user's request
-------------------------------------------
This message is displayed when the file exists into which STDERR
was to be redirected and the user requested for STDERRF to
terminate.
4.3 DOS related Errors
=======================
DOS related error messages display information on the nature of
the error and the error was the result of a failed DOS call.
Read the error message explanation and take to appropriate action
to correct the problem and try again.
4.3.1 Unable to duplicate STDERR filehandle
--------------------------------------------
This message is displayed when STDERRF can not create a duplicate
filehandle for STDERR. This duplicate filehandle is required so
that STDERR can be restored when STDERRF terminates.
9
STDERRF ERROR MESSAGES
======================
DOS error codes are:
04h - Too Many Open Files. Since STDERRF at this point has
only five standard files open and 20 files are available
to programs, the limit must be in total files opened.
Close some applications, or, at least, the files opened
in other applications, and try again.
06h - Invalid Handle. STDERR was not available to STDERRF.
STDERRF is a child program of another application that
has closed STDERR. Execute STDERRF from the DOS command
line.
4.3.2 Unable to create redirection file
----------------------------------------
STDERRF could not create the file into which STDERR was to be
redirected. The following DOS error codes are possible.
03h - Path Not Found. Check the path specified for the
redirection file as DOS could not find it. Correct and
try again.
04h - Too Many Open Files. Since STDERRF at this point has
only five standard files and one other file open and 20
files are available to programs, the limit must be in
total files opened. Close some applications, or, at
least, the files opened in other applications, and try
again.
05h - Access Denied. The redirection file already exists in
the specified path and is read-only or the file was to be
created in the root directory which was full. Change the
path of filename and try again.
4.3.3 Unable to force STDERR to redirection filehandle
-------------------------------------------------------
STDERRF could not force the STDERR filehandle to the value of the
open redirection filehandle. DOS error codes are:
04h - Too Many Open Files. Since STDERRF at this point has
only five standard files open and 20 files are available
to programs, the limit must be in total files opened.
Close some applications, or, at least, the files opened
in other applications, and try again.
06h - Invalid Handle. Something has corrupted STDERRF data.
This error should not occur.
4.3.4 Unable to load and execute program
-----------------------------------------
STDERRF could not load and execute the specified application.
The possible DOS errors are:
01h - Invalid Function. This error should not occur. If it
has something as corrupted STDERRF code segment. Try
again. If error persists, remove other applications and
try again.
10
STDERRF ERROR MESSAGES
======================
02h - File Not Found. Check the spelling of the file to
execute. Check the drive and path if used. Try again.
03h - Path Not Found. Check the spelling of the drive and
path. Try again.
04h - Too Many Open Files. Since STDERRF has not exhausted
the 20 filehandles normally available, the limit must be
in total files opened. Close some applications, or, at
least, the files opened in other applications, and try
again.
05h - Access Denied. I do not know under what conditions
that this error code is returned. If this error occurs
and is repeatable, please contact the author with the
circumstances.
08h - Not Enough Memory. Since STDERRF releases all memory
above it, there still was not enough to load and execute
the desired program. Remove any TSRs and try again.
0ah - Bad Environment. This error should not occur as
STDERRF uses the passed environment.
0ch - Bad Format. I am not sure under what conditions that
this error code is returned.
4.3.5 Unable to restore STDERR
-------------------------------
This error should not occur. If this error occurs and is repeat-
able, please contact the author with the circumstances.
4.3.6 Unable to close redirection file
---------------------------------------
This error should not occur. If this error occurs and is repeat-
able, please contact the author with the circumstances.
11
REGISTRATION
Registration Information
Mail the registration to:
Raymond Moon
16005 Pointer Ridge Drive
Bowie, MD 20716-1744
12
REGISTRATION
============
STDERRF Non-Commercial Registration Form
Name: __________________________________________________________
Company: _______________________________________________________
Address: _______________________________________________________
City, State & Zip: _____________________________________________
Registration
Basic One Computer Registration ($5.00) . . . $__________
Multiple Computer License ($1.00 each) . . . $__________
TOTAL $__________
Comments:
13
